home *** CD-ROM | disk | FTP | other *** search
/ Aminet 45 / Aminet 45 (2001)(GTI - Schatztruhe)[!][Oct 2001].iso / Aminet / dev / gui / titlebar_ic.lha / titlebar_ic / titlebar.doc < prev    next >
Text File  |  2001-05-22  |  13KB  |  352 lines
  1. TABLE OF CONTENTS
  2.  
  3. titlebar.image/--background--
  4. titlebar.image/titlebar.image
  5. titlebar.image/ObtainTBIClass
  6. titlebar.image/--background--                   titlebar.image/--background--
  7.  
  8. DESCRIPTION
  9.  
  10. The titlebar.image is a shared library which, when opened, adds to the system
  11. a public BOOPSI image class called "tbiclass". This class implements several
  12. images suitable for the use as imagery of gadgets added to the titlebar of
  13. a window, such as an "iconify" image, a "pop-up" image, and so on. Also, a
  14. general purpose "empty" (border-only) image is provided, to be used as the
  15. background of more specialized titlebar images.
  16.  
  17. The purpose of "tbiclass" is to offer developers an easy way to implement
  18. the most common additional titlebar gadgets without having to draw or
  19. code their imagery themselves, and with the added benefit of standardizing
  20. the size and appearance of this kind of gadgets. For instance, until now
  21. any developer needing an iconify gadget had to hard-code its imagery into
  22. his application, leading to a plethora of similar, but different, versions
  23. of the same gadget.
  24.  
  25. The library is freeware; if you use it, you are allowed to distribute it
  26. with your software, typically as a stand-alone file (you'll just have to
  27. add a section for it in your application's installation script).
  28.  
  29. Using "tbiclass" is very simple: you just need to open the titlebar.image
  30. library in order to add the class to the system, and then close it when you
  31. don't need the class anymore (and have freed all of its instances).
  32.  
  33. Once the class has been added to the system, you can use NewObject() in the
  34. usual way to create new "tbiclass" instances. See the "Class documentation"
  35. section to learn which tags are recognized by the class, as well as more
  36. information about the class in general.
  37.  
  38. Important note: a more refined version of "tbiclass" is also added to the
  39. system at boot time by the VisualPrefs utility (a patch to modify the look
  40. of the Amiga GUI). If the titlebar.image library, when it's opened, finds
  41. that a class named "tbiclass" already exists, it won't create another, but
  42. still will open successfully, so your code does NOT have to change to take
  43. this special case into account.
  44.  
  45. The only thing to remember is, you should NOT open the titlebar.image library
  46. if your program is launched in the Startup-sequence _before_ the line where
  47. VisualPrefs is usually started (which is just before IPrefs), or else the
  48. patch won't run correctly. If you absolutely need to place your program in
  49. the Startup-sequence before VisualPrefs/IPrefs, at least offer the user
  50. an option to avoid opening the titlebar.image library.
  51. Anyway, this shouldn't be a problem for the vast majority of applications...
  52.  
  53. The class documentation applies to both versions of "tbiclass", save where
  54. otherwise noted.
  55.  
  56.  
  57. CLASS DOCUMENTATION
  58.  
  59. Class:        tbiclass
  60. Superclass:   imageclass
  61. Include File: <images/titlebar.h>
  62.  
  63. This is a class of images suitable for use as imagery of gadgets added to
  64. a window titlebar. As of version 40, there are 6 possible "tbiclass" images
  65. to choose from:
  66.  
  67. POPUPIMAGE          A MUI "pop-up" titlebar gadget image
  68. MUIIMAGE            A MUI "settings" titlebar gadget image
  69. SNAPSHOTIMAGE       A MUI "snapshot" titlebar gadget image
  70. ICONIFYIMAGE        An "iconify" titlebar gadget image
  71. PADLOCKIMAGE        A DirOpus "padlock" titlebar gadget image
  72. TBFRAMEIMAGE        A general-purpose empty titlebar gadget image
  73.  
  74. These image types are an extension to those already offered by "sysiclass";
  75. in fact, "tbiclass" is used mostly the same way as "sysiclass" (see below
  76. for its methods and attributes).
  77.  
  78. It's worth noticing that all "tbiclass" image instances will have an
  79. Image->LeftEdge value of -1. This shouldn't be modified, and you should
  80. place your titlebar gadgets accordingly. The reason for this apparently
  81. strange behavior is that Intuition titlebar gadget images, too, work
  82. this way, and we should try to stay as compatible with Intuition as
  83. possible.
  84.  
  85. To correctly compute the horizontal position (relative to the window's
  86. right edge) of a new titlebar gadget, you should use the TBI_RELPOS()
  87. macro provided in <images/titlebar.h>. See the included test program's
  88. source for an example of how to use the TBI_RELPOS() macro.
  89.  
  90. Also, make sure you adjust your gadget's size if necessary, to adapt it
  91. to the returned image's size.
  92.  
  93. There are actually two versions of this class: a disk-based one, implemented
  94. by the freely distributable "titlebar.image" library, and another, more
  95. refined, added to the system by the VisualPrefs program at boot time.
  96. Applications needing this class should always ship with the "titlebar.image"
  97. library, and use it without worrying about the presence of VisualPrefs in the
  98. system: if it's running, its "tbiclass" version will be used automatically.
  99.  
  100. The _only_ exception to this rule is when your application is run in the
  101. Startup-sequence before VisualPrefs; in this case, you should offer the
  102. user an option to avoid opening "titlebar.image", otherwise the disk-based
  103. version of the class would be added to the system and VisualPrefs wouldn't
  104. be able to add its own version. This is, however, a very unlikely scenario;
  105. in all foreseeable cases, an application opening windows shouldn't be run
  106. so early in the Startup-sequence.
  107.  
  108. New Methods:
  109.  
  110. None.
  111.  
  112. Changed Methods:
  113.  
  114. OM_NEW - After creation of the image by the superclass, this method
  115. initializes the "tbiclass" instance data on the basis of the contents
  116. of the attributes tag list.
  117.  
  118. OM_DISPOSE - This method frees all the resources allocated in the OM_NEW
  119. method.
  120.  
  121. OM_SET - This method allows to change a few of the image attributes and
  122. checks their bounds integrity.
  123.  
  124. OM_GET - This method allows to retrieve the value of the most relevant
  125. image attributes.
  126.  
  127. IM_DRAW - This method does the actual rendering of the image, taking into
  128. account its various attributes and the screen's DrawInfo pens.
  129.  
  130. IM_DRAWFRAME - Like IM_DRAW, but uses the size specified in the impDraw
  131. message rather than the one in the image structure.
  132.  
  133. Attributes:
  134.  
  135. SYSIA_DrawInfo (IS) - This is absolutely mandatory. You MUST pass a DrawInfo
  136.                       pointer to "tbiclass" or NewObject() will fail.
  137.  
  138. SYSIA_Which (ISG) - To specify which image you want; currently there are six
  139.                     image types, defined in <images/titlebar.h>: POPUPIMAGE,
  140.                     MUIIMAGE, SNAPSHOTIMAGE, ICONIFYIMAGE, PADLOCKIMAGE and
  141.                     TBFRAMEIMAGE.
  142.  
  143. IA_Width, IA_Height (ISG) - If these are not passed, the image will have by
  144.                             default the same size of the depth gadget image.
  145.                             NOTE: prior to version 40.15, these tags were
  146.                             only recognized by the TBFRAMEIMAGE type; the
  147.                             other image types ignored them and always had
  148.                             the same size of the depth gadget image.
  149.                             [VisualPrefs' "tbiclass" still works this way.]
  150.  
  151. SYSIA_ReferenceFont (IS) - This is ignored if IA_Height is explicitly used.
  152.                            NOTE: prior to version 40.15, this tag was only
  153.                            recognized by the TBFRAMEIMAGE type; the other
  154.                            image types ignored it and always had the same
  155.                            height of the depth gadget image.
  156.                            [VisualPrefs' "tbiclass" still works this way.]
  157.  
  158. TBIA_ContentsBox (G) - To ask the image about the position and size of its
  159.                        actual "contents box" relative to the image itself.
  160.                        Said box is the part where, if you need to, you can
  161.                        add any further custom imagery. This probably only
  162.                        makes sense with TBFRAMEIMAGE images. To position
  163.                        correctly the box, you should add its Left and Top
  164.                        offsets to those of the image. Note that this
  165.                        attribute is useless for the disk-based version of
  166.                        the class, as the returned size will be always equal
  167.                        to the full image size; it is only relevant for the
  168.                        "tbiclass" version created by VisualPrefs. The value
  169.                        you pass to this tag must be a pointer to an IBox
  170.                        structure. Do NOT pass a longword pointer! (V40.12)
  171.  
  172.  
  173. PROGRAMMING EXAMPLE
  174.  
  175. An example of usage of "titlebar.image" and "tbiclass" could be given by
  176. the following code fragment:
  177.  
  178.    ...
  179.    #include "images/titlebar.h"
  180.    #include "clib/titlebarimage_protos.h"
  181.    #include "pragmas/titlebarimage_pragmas.h"
  182.  
  183.    ...
  184.    
  185.    struct Library *TitlebarImageBase;
  186.  
  187.    ...
  188.  
  189.    /* Open the library */
  190.    
  191.    if (!(TitlebarImageBase = OpenLibrary("Images/titlebar.image",40)))
  192.    {
  193.       ComplainAndExit();
  194.    }
  195.  
  196.    ...
  197.  
  198.    /* Create the image */
  199.  
  200.    if (!(iconifyimage = NewObject(NULL,"tbiclass",SYSIA_Which,ICONIFYIMAGE,
  201.                                                   SYSIA_DrawInfo,dri,
  202.                                                   TAG_END)))
  203.    {
  204.       iconifyimage = builtin_iconifyimage;  /* If really needed... */
  205.    }
  206.  
  207.    /* Use the image */
  208.  
  209.    gad->GadgetRender = iconifyimage;
  210.    ...
  211.  
  212.    /* Free the image */
  213.  
  214.    if (iconifyimage != builtin_iconifyimage) DisposeObject(iconifyimage);
  215.  
  216.    ...
  217.    
  218.    /* Close the library */
  219.    
  220.    CloseLibrary(TitlebarImageBase);
  221.    
  222.    ...
  223.  
  224. A complete example program can also be found in the distribution archive.
  225.  
  226.  
  227. TO DO
  228.  
  229. Future releases should add the following features:
  230.  
  231.  o More image types.
  232.  
  233.  o Some more code optimization.
  234.  
  235. And of course, I'm open to any suggestion about how to improve the class.
  236.  
  237.  
  238. HISTORY
  239.  
  240. 40.15 (14.5.2001)
  241.  - Now the attributes IA_Width, IA_Height and IA_ReferenceFont apply to
  242.    all image types, rather than only to the TBFRAMEIMAGE type.
  243.  
  244. 40.14 (7.2.2001)
  245.  - Now the images look correctly also on two-color screens.
  246.  
  247. 40.13 (19.1.2001)
  248.  - Corrected the height of the iconify image so that it always matches
  249.    the height of the system's zoom image.
  250.  - Added a new macro to automatically compute the correct horizontal
  251.    position of a titlebar gadget using a "tbiclass" instance as its image.
  252.  
  253. 40.12 (7.10.99)
  254.  - Added a new attribute to ask the image about its inner dimensions.
  255.  
  256. 40.11 (7.9.98)
  257.  - First public release.
  258.    
  259.  
  260. AUTHOR
  261.  
  262. Massimo Tantignone
  263. Via Campagnoli, 4
  264. 28100 Novara (NO)
  265. ITALY
  266.  
  267. E-mail: tanti@intercom.it
  268. Web:    http://www.intercom.it/~amigaws
  269.  
  270. titlebar.image/titlebar.image                   titlebar.image/titlebar.image
  271.  
  272.    NAME
  273.       titlebar.image -- create an image suitable for titlebar gadgets
  274.  
  275.    FUNCTION
  276.       The titlebar.image shared library implements a public BOOPSI image
  277.       class, called "tbiclass", which provides the most commonly used images
  278.       for gadgets added by applications to the titlebar of their windows.
  279.       Examples of this are the ubiquitous "iconify" gadget or DirOpus 5's
  280.       "padlock" gadget.
  281.       
  282.       All programs using such class will automatically get the same look for
  283.       their titlebar images. This is probably better than having myriads of
  284.       different versions of the same image...
  285.       
  286.       The titlebar.image library is freeware; the idea is that if your
  287.       software needs images for gadgets in window titlebars, you can simply
  288.       place the library into your distribution archive and let the user
  289.       install it to his machine alongside your application, which will then
  290.       be able to open and use it.
  291.  
  292.       You can use "tbiclass" just like "sysiclass"; they're both sub-classes
  293.       of "imageclass". A "tbiclass" image can be created in the usual way,
  294.       by calling NewObject() with the tags described in the class reference
  295.       documentation.
  296.  
  297.       Of course, if NewObject() fails, you should provide a built-in fallback
  298.       image for your titlebar gadget. However, as this occurrence isn't very
  299.       likely (the class requires very little memory), you can keep your
  300.       built-in images very simple.
  301.  
  302.       To be able to create and use "tbiclass" objects in an application,
  303.       you first have to open the titlebar.image library with OpenLibrary().
  304.       Once you have done this, you shouldn't close the library until all of
  305.       your "tbiclass" objects have been freed.
  306.  
  307.       For a complete description of the "tbiclass" class and its features,
  308.       see the class reference documentation in the --background-- paragraph.
  309.  
  310.    TAGS
  311.       For the full list of "tbiclass" attributes, see the class reference
  312.       documentation in the --background-- paragraph.
  313.  
  314.    WARNING
  315.       Don't close the titlebar.image library if you still have some instances
  316.       of "tbiclass" images hanging around!
  317.  
  318.    BUGS
  319.       None known.
  320.  
  321. titlebar.image/ObtainTBIClass                   titlebar.image/ObtainTBIClass
  322.  
  323.    NAME
  324.       ObtainTBIClass -- return a pointer to "tbiclass".
  325.  
  326.    SYNOPSIS
  327.       tbiclass = ObtainTBIClass()
  328.       D0
  329.  
  330.       Class *ObtainTBIClass(void);
  331.  
  332.    FUNCTION
  333.       Returns a pointer to the class implemented by the titlebar.image,
  334.       called "tbiclass". Use this pointer with care, and do not reference it
  335.       after you've closed the titlebar.image library.
  336.       
  337.    INPUTS
  338.       none
  339.  
  340.    RESULT
  341.       tbiclass - pointer to the class
  342.  
  343.    NOTES
  344.       If VisualPrefs is running, you will obtain a pointer to its special
  345.       version of "tbiclass".
  346.  
  347.    BUGS
  348.       None known.
  349.  
  350.    SEE ALSO
  351.  
  352.